.TH MP3BROADCASTER 1 "August 13, 2002" "Apple Computer, Inc."
.SH NAME
MP3Broadcaster \- MP3 file playlist broadcaster
.SH SYNOPSIS
.B MP3Broadcaster
[-v] [-d] [-x] [-X] [-a ipAddress] [-p portNum] [-l filename] [-w filename] [-e filename] -c filename
.SH DESCRIPTION
.I MP3Broadcaster
broadcasts a set of MP3 files listed in a special playlist file format. If the MP3 source files
referenced in the playlist contain meta-data suitable for display in clients then this too is 
streamed to a server on a separate TCP connection.
.PP
.I MP3Broadcaster 
is intended to be used with
.IR QuickTimeStreamingServer (1)
which handles the details of delivering one or more MP3 broadcast streams to MP3 clients.
.I MP3Broadcaster 
cannot be used to deliver a MP3 broadcast stream directly to a MP3 client. A MP3 stream
reflector server such as
.IR QuickTimeStreamingServer (1)
or
.I Shoutcast
must be used to deliver the stream to clients. You may also use
.I MP3Broadcaster
with other 'Shoutcast-compatible' servers such as
.I Icecast.
.PP
.I MP3Broadcaster
requires a
.B \-c
command line option followed by a playlist config file path. All other command line options
are not required. If 
.I MP3Broadcaster
is used with no options it just prints a usage string to the command line. 
.PP
A command line option of
.B \-d
must be specified if you want
.I MP3Broadcaster
to run as a foreground shell process. (It defaults to running as a background 
shell process otherwise.)
.PP
The playlist configuration file specified with a
.B \-c
command line option is a plain ASCII text file with configuration parameters
for the MP3 broadcast specified one per line. A configuration keyword must be
specified on each line followed by one or more spaces followed by the
value to be set associated with that keyword. If the value is a character
string containing spaces it must be surrounded by double quotes.
.PP
For example, a playlist configuration file might be given as:
.RS
.nf

destination_ip_address 90.22.34.5
destination_base_port 8000
max_upcoming_list_size 1
play_mode sequential_looped
recent_songs_list_size 1
playlist_file /home/bozo/jazz.play
working_dir /home/bozo
logging enabled
show_current disabled
show_upcoming disabled
broadcast_name "Steve's Broadcaster"
broadcast_password hackme
broadcast_url http://myserver.nowhere.com:8000
broadcast_mount_point /HotJazz
broadcast_genre Jazz

.fi
.RE
which would cause
.I MP3Broadcaster
to start broadcasting the playlist named "jazz.play" in the directory
path "/usr/bozo" to the server located at IP address 90.22.34.5 on TCP
port number 8000. Assuming that the server at this IP address is
.IR QuickTimeStreamingServer (1)
and has been configured to accept MP3 streams on port 8000 with a MP3 broacast
password of "hackme" then the stream will be accepted by the server and be ready
to forward the stream to any client that requests the mountpoint of "/HotJazz".
.PP
The playlist file like the playlist configuration file is a plain text ASCII file
that list the MP3 files to be broadcast. The format of the file is a single line containing
string "*PLAY-LIST*" followed by a list of file paths to individual MP3 files with an optional
parameter of a number from 1 to 10 that designates the weight of the file. (This optional
parameter is used with the "play_mode" keyword associated with the value "weighted_random".
When this play mode is specified the files will be picked at random according to the
specfied weight.)
.PP
.PP
For example, a playlist file might be given as:
.RS
.nf

*PLAY-LIST*
"/home/bozo/my_first_song.mp3" 6
"/home/bozo/my_second_song.mp3" 7
"/home/bozo/my_favorite_song.mp3" 10
"/home/bozo/my_last_song.mp3" 3

.fi
.RE
which would cause each file in the playlist to be broadcast at random according to the
weight specified. (Assuming a play_mode of "weighted_random" is specified
in the configuration file.) If the optional weight parameter is not present
in the playlist file then a value of 10 is assumed. The weight parameter is
ignored if the play_mode is specfied as "sequential" or "sequential_looped".
.PP
Text lines in the playlist configuration file or the playlist file that begin
with the '#' character will be treated as comments and will not be read by
.I MP3Broadcaster.
.PP
The
.I MP3Broadcaster
may be run in "preflight" mode by using the
.B \-x
option which will cause the configuration file to be read
and the MP3 files to be scanned for potential errors. The
.I MP3Broadcaster
will not broadcast any files when run in this mode. You can
use this mode to check your configuration file for errors.
.SH OPTIONS
.PP
The 
.I MP3Broadcaster
accepts the following command line options:
.TP
.B \-v
Displays the version and build information.
.TP
.B \-d
Runs
.I MP3Broadcaster
as a foreground shell process. (The default is to run as a background
shell process.)
.TP
.B \-x
Runs
.I MP3Broadcaster
in preflight mode. (See description above.)
.TP
.B \-X
Causes
.I MP3Broadcaster
to scan the MP3 files listed in the playlist file for errors.
.TP
.BI \-a " <ipaddr>"
Is the broadcast IP address as given by the argument
.I <ipaddr>.
The default if not specified in the playlist configuration or with
this option is the local loopback address. If this value is specfied
in the configuration file then using this option overrides that value.
.TP
.BI \-p " <portnumber>"
Is the TCP port number to be used in the broadcast as given by the argument
.I <portnumber>.
The default if not specified in the playlist configuration or with
this option is port number 8000. If this value is specified
in the configuration file then using this option overrides that value.
.TP
.BI \-c " filename"
Is the path to the playlist configuration file as given by the argument
.I filename.
The keyword values listed in
.I filename
must be one per line. Leading and trailing white space are not part of the
symbol name.  Lines starting with # are ignored.
.TP
.BI \-l " filename"
Is the path to the playlist file as given by the argument
.I filename.
The MP3 file paths listed in
.I filename
must be one per line followed by an option weight value of between 1 to 10.  
If the fle path names contains blanks then the path must be surrounded with
double quotes. The first line of 
.I filename
must be the string "*PLAY-LIST*". Lines starting with # are ignored. Any value
specified with this option overrides a value given in the configuration file.
.TP
.BI \-w " path"
Is the path to the directory for temporary files. Any value specified with this 
option overrides a value given in the configuration file.
.TP
.BI \-e " filename"
Is the path to an error log file as given by the argument
.I filename.
.SH "SEE ALSO"
QuickTimeStreamingServer(1), PlaylistBroadcaster(1)
.SH LIMITATIONS
The
.I MP3Broadcaster
does not perform down-sampling or re-encoding of the source MP3 files. If the source
MP3 files are encoded at a bit rate too high for reliable streaming then they must
be re-encoded by other means.
